craft-mesh-ops: mesh operations, a BVH and primitives for the 3D apps - #1233

Summary

This adds the crate craft-mesh-ops (crates/mesh-ops), the craft-mesh-ops row of RFC-0032 (storytold/craft-contrib#50). It holds the triangle-mesh code that TextureCraft and MaterialCraft each keep a copy of: area-weighted normals, MikkTSpace tangents, welding, UV unwrapping, the UV-space G-buffer, primitives with UVs, a BVH and the orbit camera. The crate has no UI, no file or network I/O and no unsafe code. No app uses it yet. Each app switches to it in its own pull request.

The code is TextureCraft crates/geom at 386630e, with Mesh::subdivided from MaterialCraft crates/geom/src/mesh.rs at 3133062. The BVH is TextureCraft's binned SAH builder on all three axes with its median fallback.

• The functions at the crate root (bounds, smooth_normals, tangents, weld, unwrap_uvs), UvGBuffer::from_slices and Bvh::from_slices take plain slices: positions and normals as [f32; 3], UVs as [f32; 2], triangle indices as u32. tangents returns [f32; 4] with the bitangent sign in w, and returns Invalid for a vertex whose triangle corners get different tangent frames. Before any work, bounds checks that every value is finite, and the other functions also check the counts against Limits and every index; each returns a MeshOpsError (Invalid, TooLarge, OutOfMemory).
• Limits has a default for each count: 20,000,000 vertices and triangles (the craft-mesh values), 2,048 segments along one direction of a primitive, a G-buffer side of 8,192, 2^26 G-buffer texels, 2^32 texels visited by the G-buffer rasterizer, 2^26 entries in the G-buffer's per-band triangle lists, and 4,000,000 triangles for one unwrap. The last six are this crate's own values. Sums and products are checked with checked_ arithmetic before any allocation, and allocations go through try_reserve_exact or try_reserve, so a failed allocation returns OutOfMemory.
• try_append, try_subdivided, the try_ primitives, UvGBuffer::try_new, Bvh::try_new, Mesh::try_compute_normals, Mesh::try_compute_tangents, unwrap::weld_ids and unwrap::auto_unwrap return the error. The moved forms keep their signatures: they clamp, return the mesh unchanged or return an empty result.
• Tangents come from MikkTSpace, which glTF 2.0 names for meshes without tangents: client implementations "SHOULD calculate tangents using default MikkTSpace algorithms" (glTF 2.0). UVs and the bitangent sign follow glTF.
• The features are bvh (Bvh, Hit), parallel (rayon) and serde (OrbitCamera), all off by default.
• The crate README has the limits table and Origin and Migration tables. The root README.md, Cargo.toml, NOTICE and ATTRIBUTION.md list the crate. Flat normals, triangulation with holes, extrusion of 2D outlines and a conversion from craft_mesh::Mesh, which the RFC row also names, are not in this pull request.
• mikktspace 0.3.0 is MIT OR Apache-2.0 (crates.io). Its src/generated.rs carries the 2011 notice of Morten S. Mikkelsen's C original, which crates/mesh-ops/ATTRIBUTION.md reproduces unchanged.
• No workflow changes. Adding the crate to a wasm32 check is a separate pull request.

Faults fixed in the moved code, each with a test:

• Mesh::from_parts and compute_tangents passed a mesh with an index past its vertices to MikkTSpace, which panicked. The index check and its two tests are from TextureCraft #386 by simonhull.
• Submesh start + count and the index offsets of append wrapped u32, and validate added them as usize and accepted a range that does not cover whole triangles. They are now checked in u64 and have to start and end on a triangle.
• Mesh::validate checked only the positions for non-finite values. It now also rejects non-finite normals, UVs, tangents and colors.
• compute_tangents passed non-finite positions to MikkTSpace. A non-finite mesh now gets per-triangle tangents without the MikkTSpace call, and so does a mesh whose triangles all become degenerate after the division below. Positions and UVs outside 1e-6 to 1e6, and normals that are not near unit length, are divided by their largest magnitude first, so finite input gives finite normals and tangents.
• The primitives built a mesh from a NaN size, and the box panicked in clamp on a negative or NaN half size and gave NaN UVs for a zero one. For a non-finite size or one that overflows a coordinate, they return an empty mesh and the try_ forms an error. For a segment count over the limit, the try_ forms return an error and the other forms clamp the count.
• Mesh::bounds and the BVH bounds dropped a NaN position through min and max ("Returns the minimum of the two numbers, ignoring NaN", f32::min). The slice functions return an error, Mesh::bounds leaves non-finite positions out, and the BVH leaves out a triangle with a non-finite corner. Rejecting NaN explicitly is this crate's own rule.
• A BVH query with a NaN box reported unrelated triangles, and a ray with a NaN direction visited the tree. A ray with a non-finite origin or direction, a zero direction or a NaN tmax, a nearest query with a non-finite point or a NaN or negative distance, and a box query with a NaN coordinate now find nothing and make no callback.
• append left the attribute arrays shorter than the positions when one side had no tangents, normals or UVs. It fills them in, and gives a side with submeshes and no material list one unnamed material.
• subdivided took midpoints as (a + b) * 0.5, which overflows near f32::MAX, multiplied submesh ranges unchecked, and had no polygon-diagonal flags to carry. It takes half-sums, keeps each submesh on its own triangles and rebuilds the flags for the four children.
• Mesh::tri multiplied the triangle index unchecked. normalize_to overflowed on large finite coordinates and left a mesh with a radius under 1e-4 too small.
• BVH lengths and child indices were cast to u32 unchecked. UvGBuffer::new multiplied the caller's sides and allocated without a cap, and wrote NaN weights for a triangle whose texel coordinates overflow. auto_unwrap added submesh fields unchecked and changed the mesh before it returned an error.
• The ray test's absolute 1e-12 determinant cutoff missed small triangles. The cutoff now follows the triangle's size and is unchanged where the product of the edge and direction lengths is 1 or more. Bvh::nearest skipped a point exactly at max_dist.
• auto_unwrap and weld_ids gave a different result for the same mesh at a very large or very small scale. OrbitCamera::frame stored NaN for a box it cannot frame.

Changes since the first review:

• The UV G-buffer visited every texel of each triangle's clipped bounding box, and grew one list entry per band of 32 rows a triangle reached, with no cap. It now makes a first pass that checks the triangles visited against max_triangles, the clipped box texels against max_gbuffer_work and the band entries against max_gbuffer_bin_entries, and returns TooLarge before it reserves the band lists (in one piece) or the texel buffers. UvGBuffer::try_new also checks the mesh's vertex and triangle counts.
• auto_unwrap applies the default Limits instead of no vertex cap. The unwrap checks the vertex count, the triangle count and the triangles its submeshes list before any work, and the output vertex count as it builds. Charts are grouped by material in one pass instead of one scan of all charts per material.
• A face joins a UV chart only when its projection, computed in f64, does not overlap the chart's faces. A layout that fits only at scale zero grows the packing square.
• Smooth normals and the unwrap's face normals, areas and chart projections are computed in f64 from the positions as given, so a small face far from the origin keeps its normal and its chart plane.
• MikkTSpace results are kept per triangle corner, and Mesh::compute_tangents splits a vertex whose corners get different frames. A mesh with more than 2,048 triangles around one welded vertex gets the per-vertex fallback.
• try_subdivided rejects a submesh that names a missing material, as Mesh::validate does, and reserves every array it copies and each triangle's midpoints before adding them.
• The try_ primitives reserve their vertices and indices. Mesh::map_material_uvs copies a shared vertex's normal, tangent, UV and color only where the mesh has that attribute, so absent arrays stay empty.
• A BVH without triangles has no nodes. Bvh::nearest finds the nearest point in f64, inside thin triangles and next to a zero-length edge.
• OrbitCamera's orthographic projection and pan clamp the field of view as the perspective projection does, and project returns None behind the camera in orthographic mode. OrbitCamera::frame keeps the framed camera only when its view-projection is finite.
• surface_at and the rounded box keep the direction of vectors whose squared length overflows f32. The cylinder's side UVs are the same at every size.

TextureCraft #277 (simonhull), #416 and #253 (SteamSmith), #413 (Rebornim) and #360 (iceteabln) are open on the same files. The finite-value check that #253 adds to Mesh::validate is also in this pull request (see above); #253's ±1e6 UV range check is not. This pull request also splits a vertex whose corners get different tangent frames (see above). The other changes of these pull requests are not included here, and the other behavior they change (tangents on quads, the UV range, G-buffer coverage on shared edges, the ray traversal) is as it is in TextureCraft today.

Validation

New tests, each failing without its fix:

• mesh.rs: from_parts_refuses_an_out_of_range_index_without_crashing and tangents_of_a_mesh_with_an_out_of_range_index_fall_back_without_crashing (both from font-catalog: a face cache for apps' own face objects #386), submesh_ranges_and_append_reject_overflow, validate_rejects_unaligned_and_overflowing_submeshes, tangents_reject_non_finite_and_survive_extreme_positions, tangents_skip_mikktspace_when_dividing_makes_every_triangle_degenerate, tangents_stay_perpendicular_to_very_long_normals, normals_of_many_large_triangles_at_one_vertex_do_not_overflow, bounds_reject_non_finite_positions, append_keeps_attributes_aligned, append_keeps_unnamed_materials_apart, subdivision_preserves_large_finite_midpoints, subdivision_checks_submeshes_and_diagonals, tri_rejects_overflowing_triangle_index, normalize_large_finite_meshes, normalize_handles_the_largest_radii_and_the_smallest_meshes
• primitives.rs: primitives_reject_non_finite_parameters, box_rejects_negative_nan_and_zero_half_size, primitives_reject_sizes_that_overflow, primitives_reject_oversized_segment_counts
• bvh.rs: bvh_rejects_non_finite_queries_without_callbacks, bvh_leaves_out_non_finite_triangles, bvh_slices_check_limits_indices_and_positions, nearest_includes_points_exactly_at_the_distance, ray_hits_do_not_depend_on_the_size_of_the_triangle
• gbuffer.rs: gbuffer_rejects_huge_dimensions, gbuffer_skips_triangles_whose_texel_coordinates_overflow, gbuffer_slices_reject_bad_indices_and_uvs, gbuffer_rejects_overlapping_box_work_before_rasterization, gbuffer_rejects_excess_band_entries, gbuffer_mesh_constructor_respects_count_limits, gbuffer_work_counts_clipped_boxes_and_skips_off_image, gbuffer_budgets_are_checked_before_the_texels_are_reserved
• unwrap.rs: unwrap_rejects_bad_submeshes_and_positions_before_changing_the_mesh, unwrap_slices_return_source_vertices_and_respect_limits, unwrap_gives_the_same_layout_at_extreme_scales, weld_ids_survive_extreme_and_non_finite_positions, auto_unwrap_respects_mesh_count_limits, unwrap_core_stops_at_output_vertex_limit, unwrap_many_materials_groups_charts_once
• camera.rs: frame_leaves_the_camera_unchanged_for_a_box_it_cannot_frame, frame_keeps_the_view_finite

Tests added with the review changes:

• mesh.rs: tangents_split_vertices_shared_by_opposite_frames, tangents_of_a_fan_around_one_vertex_do_not_exhaust_the_stack, a_small_triangle_far_from_the_origin_keeps_its_normal_and_tangent, material_uvs_leave_absent_attributes_absent, subdivision_keeps_the_input_vertices_and_materials
• unwrap.rs: a_small_triangle_far_from_the_origin_unwraps_in_its_own_plane, a_layout_that_fits_only_at_zero_scale_is_not_accepted, charts_do_not_overlap_where_a_flat_surface_winds_past_a_full_turn, faces_that_only_share_edges_and_corners_stay_in_one_chart, small_faces_that_overlap_a_large_one_start_another_chart, thin_faces_that_overlap_start_another_chart
• bvh.rs: a_tree_without_triangles_has_no_nodes, nearest_finds_a_point_inside_a_thin_triangle, nearest_measures_a_triangle_with_a_collapsed_edge
• camera.rs: field_of_view_is_clamped_the_same_way_in_every_mode, orthographic_projection_finds_nothing_behind_the_camera
• primitives.rs: a_scaled_primitive_is_the_unit_primitive_scaled
• gbuffer.rs: surface_keeps_the_direction_of_long_finite_vectors

The OutOfMemory results have no test, because the allocation cannot be made to fail in a test.

The 30 moved tests pass unchanged, apart from rustfmt wrapping two statements at this repository's 150 columns:

• bvh.rs: nearest_point_matches_brute_force, traversal_stack_spills_in_lifo_order, ray_hits_sphere_at_expected_distance, matches_brute_force, box_query_finds_overlapping_triangles, large_coplanar_plate_does_not_degrade_leaf_sizes, clustered_coplanar_fallback_partitions_nodes, coincident_centroids_still_partition_large_and_small_triangles
• mesh.rs: normals_and_tangents_of_a_quad, wire_edges_leave_out_polygon_diagonals, uv_seams_are_where_the_uv_layout_splits, uv_seams_join_positions_with_opposite_signed_zero, uv_seams_between_materials_belong_to_both_materials, validate_catches_bad_indices, append_offsets_indices_and_materials, material_uvs_remap_and_split_shared_vertices, and MaterialCraft's subdivision_shares_edge_midpoints
• primitives.rs: primitives_are_well_formed, preview_orb_is_well_formed_with_domed_panels, material_ball_has_two_materials
• gbuffer.rs: half_triangle_covers_texels_with_centers_inside, overlapping_and_degenerate_triangles, sphere_surface_lies_on_the_sphere
• unwrap.rs: sphere_unwraps_without_overlaps, cube_unwraps_without_overlaps, torus_and_material_ball_unwrap, many_tiny_charts_still_fit, degenerate_and_empty_meshes_do_not_fail
• camera.rs: center_ray_points_at_target_and_projection_inverts, pitch_is_clamped_and_zoom_bounded

On main at 6d620e9, on Linux, at 84816686:

• cargo fmt --all -- --check
• cargo clippy -p craft-mesh-ops --all-targets -- -D warnings, and with --all-features
• cargo check --workspace --tests
• cargo test -p craft-mesh-ops --lib -- mesh:: (30 passed) and -- unwrap:: (18 passed), and cargo test -p craft-mesh-ops --all-features --lib -- gbuffer:: bvh:: camera:: primitives:: (42 passed): 90 tests
• cargo check -p craft-mesh-ops --target wasm32-unknown-unknown --all-features

The branch merges cleanly with main at 948b5c2. The Workspace workflow runs the workspace clippy and tests, and the Rust 1.95 check, on this pull request.

Summary by CodeRabbit

• New Features
  • Added tools for creating and editing triangle meshes, including smooth normals, tangents, vertex welding, subdivision, and automatic UV unwrapping.
  • Added UV-space surface mapping, an orbit camera with projection and viewport-ray support, and optional acceleration for ray-hit, occlusion, nearest-point, and box queries.
  • Added built-in meshes, including spheres, cubes, cylinders, rounded boxes, and planes.
  • Added input validation and configurable limits for mesh operations.
• Documentation
  • Added library guides and third-party attribution and license notices.